\chapterbegin Chapter 6. Running\\\TeX

The best way to learn how to use \TeX\ is to use it. Thus, it's high time
for you to sit down at a computer terminal and interact with the \TeX\
system, trying things out to see what happens. Here are some small but
complete examples suggested for your first encounter.
↑(Running the program)

Caution: This chapter is rather a long one. Why don't you stop reading
now, and come back to it tomorrow?

\smallskip OK, let's suppose that you're rested and excited about having a
trial run of \TeX. Step-by-step instructions for using it appear in this
chapter. First do this: Go to the lab where the graphic output device is,
since you will be wanting to see the output that you get---it won't really
be satisfactory to run \TeX\ from a remote location, where you can't hold
the generated documents in your own hands. Then log in; and start \TeX. \
(You may have to ask somebody how to do this on your local computer; usually
the operating system prompts you for a command and you type `|TeX|' or
`|run| |tex|' or something like that.)

When you're successful, \TeX\ will welcome you with a message such as
\ttbegin
This is TeX, Version 1.0 (format=plain 83.7.15)
**
\ttend
The `↑{.**}' is \TeX's way of asking you for an input file name.

Now type `↑{*relax}' (including the backslash), and \<carriage-return>
(or whatever is used to mean ``end-of-line'' on your terminal).
\TeX\ is all geared up for action, ready to read a long manuscript; but
you're saying that it's all right to take things easy, since this is
going to be a real simple run. In fact, |\relax| is a control sequence
that means ``do nothing.''

The machine will type another asterisk at you. This time type something
like `|Hello?|' and wait for another ↑{asterisk}. Finally type `↑{*end}',
and stand back to see what happens.

\TeX\ should respond with `↑{.[1]}' (meaning that it has finished page@1
of your output); then the program will halt, probably with some
indication that it has created a file called `|texput.dvi|'. \ (\TeX\
uses the name ↑{.texput} for its output when you haven't specified any
better name in your first line of input; and ↑{.dvi} stands for
``↑{device independent},'' since |texput.dvi| is capable of
being printed on almost any kind of output device.)

Now you're going to need some help again from your friendly local
computer hackers. They will tell you how to produce hardcopy from
|texput.dvi|. And when you see the hardcopy---Oh, glorious day!---you
will see a magnificent `Hello?' and the page number `1' at the bottom.
Congratulations on your first masterpiece of fine printing.

\smallbreak
The point is, you understand now how to get something through the whole cycle.
It only remains to do the same thing with a somewhat longer document.
So our next experiment will be to work from a file instead of typing
the input online.

Use your favorite text editor to create a file called ↑{.story.tex} that
contains the following 18 lines of text (no more, no less):
$$\halign{\hbox to\the\parindent{\hfil\sevenrm#\ \ }&#\hfil\cr
1&|\hrule|\cr\noalign{↑(*hrule)}
2&|\vskip 1in|\cr\noalign{↑(*vskip)}
3&|\ctrline{\bf A SHORT STORY}|\cr\noalign{↑(:ctrline)}
4&|\vskip 6pt|\cr
5&|\ctrline{\sl by A. U. Thor}|\cr\noalign{↑(Thor)}
6&|\vskip .5cm|\cr
7&|Once upon a time, in a distant|\cr
8&|  galaxy called \"O\"o\c c,|\cr\noalign{↑(:")↑(:c)}
9&|there lived a computer|\cr
10&|named R.@J. Drofnats.|\cr\noalign{↑(Drofnats)}
11&||\cr
12&|Mr.@Drofnats---or ``R. J.,'' as|\cr
13&|he preferred to be called---|\cr
14&|was happiest when he was at work|\cr
15&|typesetting beautiful documents.|\cr
16&|\vskip 1in|\cr
17&|\hrule|\cr
18&|\vfill\eject|\cr\noalign{↑(*vfill)↑(:eject)}}$$
(Don't type the numbers at the left of these lines, of course; they are present
only for reference.) \ This example is a bit long, and more than a bit silly;
but it's no trick for a good typist like you and it will give you some
worthwhile experience, so do it. For your own good. And think about what
you're typing, as you go; the example introduces a few important features
of \TeX\ that you can learn as you're making the file.

Here is a brief explanation of what you have just typed: Lines 1 and@17
put a horizontal ↑{rule} (a thin line) across the page. Lines 2 and@16
skip past one inch of space; `|\vskip|' means ``vertical skip,'' and this
extra space will separate the horizontal rules from the rest of the copy.
Lines 3 and@5 produce the title and the author name, centered, in boldface
and in slanted type. Lines 4 and@6 put extra white space between those
lines and their successors. \ (We shall discuss units of measure like
`|6pt|' and `|.5cm|' in Chapter@10.)

The main bulk of the story appears on lines 7--15, and it consists of
two ↑{paragraphs}. The fact that line@11 is blank informs \TeX\ that
line@10 is the end of the first paragraph; and the `|\vskip|' on line@16
implies that the second paragraph ends on line@15, because vertical
skips don't appear in paragraphs. Incidentally, this example seems
to be quite full of \TeX\ commands; but it is atypical in that respect,
because it is so short and because it is supposed to be teaching things.
Messy constructions like |\vskip| and |\ctrline| can be expected at the
very beginning of a manuscript, unless you're using a canned format, but
they don't last long; most of the time you will find yourself typing
straight text, with relatively few control sequences.

And now comes the good news, if you haven't used computer typesetting
before:  You don't have to worry about where to break lines in a paragraph
(i.e., where to stop at the right margin and to begin a new line), because
\TeX\ will do that for you. Your manuscript file can contain long lines or
short lines, or both; it doesn't matter. This is especially helpful when
you make changes, since you don't have to retype anything except the words
that changed. {\sl Every time you begin a new line in your manuscript file
it is essentially the same as typing a space.} When \TeX\ has read an
entire paragraph---in this case lines 7 to@10---it will try to break up
the text so that each line of output, except the last, contains about the
same amount of copy; and it will hyphenate words if necessary to keep the
spacing consistent, but only as a last resort.

Line 8 contains the strange concoction
\ttbegin
\"O\"o\c c
\ttend
and you already know that |\"| stands for an ↑{umlaut} accent. The
|\c| stands for a ``↑{cedilla}'', so you will get ``\"O\"o\c c'' as the
name of that distant galaxy.

The remaining text is simply a review of the conventions that we discussed
long ago for dashes and quotation marks; except that the `|@|' signs in
lines 10 and@12 are a new wrinkle. These are called {\sl ↑{ties}}, because
they tie words together; i.e., \TeX\ is supposed to treat `|@|' as a
normal space but not to break between lines there.
A good typist will use ties within names, as shown in our
example; further discussion of ties appears in Chapter@14.

Finally, line@18 tells \TeX\ to `|\vfill|', i.e., to fill the rest of
the page with white space, and to `|\eject|' the page.

\smallskip Now you're ready for Experiment@2: Get \TeX\ going again.
This time when the machine says `|**|' you should answer `|story|', since
that is the name of the file where your input resides. \ (The file
could also be called by its full name `|story.tex|', but \TeX\ automatically
supplies the suffix `|.tex|' if no suffix has been specified.)

You might wonder why the first prompt was `|**|', while the subsequent
ones are `|*|'; the reason is simply that the first thing you type to
\TeX\ is slightly different from the rest: If the first character of your
response to `|**|' is not a backslash, \TeX\ automatically inserts
`↑{*input}'. Thus you can usually run \TeX\ by merely naming your input
file. \ (Previous \TeX\ systems required you to start by typing `|\input
story|' instead of `|story|', and you can still do that; but most \TeX\
users prefer to put all of their commands into a file instead of typing
them on line, so \TeX\ now spares them the nuisance of starting out with
|\input| each time.) \ Recall that in Experiment@1 you typed `|\relax|';
that started with a backslash, so |\input| was not implied.

\danger There's actually another difference between `|**|' and `|*|': If the
first character after |**| is an ↑{ampersand} (\thinspace`|&|'\thinspace),
\TeX\ will replace its memory with a precomputed format file before
proceeding. Thus, for example, you can type `|&plain \input story|' or
even `|&plain story|' in response to `|**|', if you are running some
version of \TeX\ that might not have the plain format preloaded.

\danger Incidentally, many systems allow you to invoke \TeX\ by typing a
one-liner like `|tex story|' instead of waiting for the `|**|'; similarly,
`|tex \relax|' works for Experiment@1, and `|tex &plain story|' loads the
plain format before inputting the |story| file.  You might want to try
this, to see if it works on your computer, or you might ask somebody if
there's a similar shortcut.

As \TeX\ begins to read your story file, it types `|(story.tex|' (possibly
with a version number for more precise identification, depending on your
local operating system). Then it types `|[1]|', meaning that page@1 is done;
and `|)|', meaning that the file has been entirely input.

\TeX\ will now prompt you with `|*|', because the file did not contain
`↑{*end}'. Enter |\end| into the computer now, and you should get a file
|story.dvi| containing a typeset version of Thor's story. As in Experiment@1,
you can proceed to convert |story.dvi| into hardcopy; go ahead and do that now.
The typeset output won't be shown here, but you can see the results by
doing the experiment personally.

\exercise Statistics show that only 7.4 of 10 people who read this manual
actually type the |story.tex| file as recommended, but that those people
learn \TeX\ best. So why don't you join them?
\answer Laziness and/or obstinacy.

\exercise Look closely at the output of Experiment@2, and compare it to
|story.tex|\thinspace: If you followed the instructions carefully, you
will notice a typographical error. What is it, and why did it sneak in?
\answer There's an unwanted space after `called---', because (as the book
says) \TeX\ treats the end of a line as if it were a blank space. That
blank space is usually what you want, except when a line ends with a
hyphen or a dash; so you should {\sc WATCH OUT} for lines that end with
hyphens or dashes.

With Experiment 2 under your belt, you know how to make a document from a
file. The remaining experiments in this chapter are intended to help you
cope with the inevitable anomalies that you will run into later; we will
intentionally do things that will cause \TeX\ to ``squeak.''

But before going on, it's best to fix the error revealed by the previous
output (see exercise 6.2): Line@13 of the |story.tex| file should be changed to
\ttbegin
he preferred to be called---% error has been fixed!
\ttend
The `|%|' sign here ↑(percent) is a feature of plain \TeX\ that we haven't
discussed before: It effectively terminates a line of your input file,
without introducing the blank space that \TeX\ ordinarily inserts when
moving to the next line of input. Furthermore, \TeX\ ignores everything
that you type following a |%|, up to the end of that line in the file;
you can therefore put comments into your manuscript, knowing that the
comments are for your eyes only.

Experiment 3 will be to make \TeX\ work harder, by asking it to set the
story in narrower and narrower columns. Here's how: After starting the
program, type
\ttbegin
\hsize=4in \input story
\ttend
in response to the `|**|'. This means, ``Set the story in a 4-inch column.''
More precisely, ↑{*hsize} is a primitive of \TeX\ that specifies the horizontal
size, i.e., the width of each line in the output when a paragraph is being
typeset; and ↑{*input} is a primitive that causes \TeX\ to read the specified
file. Thus, you are instructing the machine to change the normal setting of
|\hsize| that was defined by plain \TeX, and then to process |story.tex|
under this modification.

\TeX\ should respond by typing something like `|(story.tex [1])|' as
before, followed by `|*|'. Now you should type
\ttbegin
\hsize=3in \input story
\ttend
and, after \TeX\ says `|(story.tex [2])|' asking for more, three more lines
\ttbegin
\hsize=2.5in \input story
\hsize=2in \input story
\end
\ttend
to complete this four-page experiment.

Don't be alarmed when \TeX\ screams `|Overfull| |\hbox|' several times as
it works at the 2-inch size; that's what was supposed to go wrong during
Experiment@3. The problem is that there is no good way to break the given
paragraphs into lines that are exactly two inches wide, without making
the spaces between words come out too large or too small. Plain \TeX\
has been set up to ensure rather strict tolerances on all of the lines it
produces:
$$\displayvbox{
    \hbox expand-1em{you don't get spaces between words
      narrower than this,\ and}
    \hbox expand+1.679895em{you don't get spaces between words wider
      than this.}}$$
If there's no way to meet these restrictions, you get an ↑{overfull box}.
And with the overfull box you also get (1)@a warning message, printed
on your terminal, and (2)@a big black bar inserted at the right of the
offending box, in your output. \ (Look at page@4 of the output from
Experiment@3; the overfull boxes should stick out like sore thumbs.
On the other hand, pages 1--3 should be perfect.)

Of course you don't want overfull boxes in your output, so \TeX\ provides
several ways to remove them; that will be the subject of our Experiment@4.
But first let's look more closely at the results of Experiment@3, since
\TeX\ reported some potentially valuable information when it was forced
to make those boxes too full; you should learn how to read this data:
\ttbegin
Overfull \hbox (1.02238pt too wide) in paragraph at lines 7--11
\tenrm tant galaxy called []O↑↑So↑↑Xc, there lived|vert
Overfull \hbox (0.50156pt too wide) in paragraph at lines 7--11
\tenrm a com-puter named R. J. Drof-nats. |vert
Overfull \hbox (5.42514pt too wide) in paragraph at lines 12--16
\tenrm he pre-ferred to be called---was hap-|vert
\ttend
Each overfull box is correlated with its location in your input file
(e.g., the first two were generated when processing the paragraph on
lines 7--11 of |story.tex|), and you also learn by how much the copy
sticks out (e.g., 1.02238 points).

Notice that \TeX\ also shows the contents of the overfull boxes in
abbreviated form. For example, the last one has the words `he preferred
to be called---was hap-', set in font |\tenrm| (10-point roman type);
the first one has a somewhat curious rendering of `\"O\"o\c c', because the
accents appear in strange places within that font. In general, when you
see `↑{.[]}' in one of these messages, it stands either for
the paragraph indentation or for some sort of complex construction;
in this particular case it stands for an umlaut that has been raised
up to cover an `O'.

\dangerexercise Can you explain the `\vert' that appears after
`|lived|' in that message? 
\answer It represents the heavy bar that shows up in
your output. \ (This bar wouldn't be present if ↑{*overfullrule} had been
set to zero, nor is it present in an underfull box.)

\dangerexercise Why is there a space before the `\vert' in `|Drof-nats.
|\vert'\thinspace?
\answer This is the ↑{*parfillskip} space that ends the paragraph.
In plain \TeX\ the parfillskip is zero when the last line of paragraph
is full; hence no space actually appears before the rule in the output
of Experiment@3. But all hskips show up as spaces in an overfull box
message, even if they're zero.

You don't have to take out pencil and paper in order to write down the
overfull box messages that you get before they disappear from view, since
\TeX\ always writes a ``↑{transcript}'' or ``↑{log file}'' that records what
happened during each session. For example, you should now have a file
called |story.log| containing the transcript of Experiment@3, as well
as a file called |texput.log| containing the transcript of Experiment@1. \
(The transcript of Experiment@2 was probably overwritten when you did
number@3.) \ Take a look at |story.log| now; you will see that the overfull
box messages are accompanied not only by the abbreviated box contents,
but also by some strange-looking data about hboxes and glue and kerns and
such things. This data gives a precise description of what's in that
overfull box; \TeX\ wizards will find such
listings important, if they are called upon to diagnose some mysterious
error, and you too may be able to understand \TeX's internal code some day.

The abbreviated forms of overfull boxes show the hyphenations that
\TeX\ tried before it resorted to overfilling. The ↑{hyphenation} algorithm,
which is described in Appendix@H\null, is excellent but not perfect; for
example, you can see from the messages in |story.log| that \TeX\ finds the
hyphen in `pre-ferred', and it can even hyphenate `Drof-nats'. Yet it
discovers no hyphen in `galaxy', and every once in
awhile an overfull box problem can be cured simply by giving \TeX\ a hint
about how to hyphenate some word more completely. \ (We will see later that
there are two ways to do this, either by inserting ↑{discretionary hyphens}
as in `\hbox{|gal\-axy|}' or by saying `\hbox{|\hyphenation{gal-axy}|}' at the
beginning of your manuscript.)

In the present example, hyphenation is not a problem, since \TeX\ found
and tried all the hyphens that could possibly have helped. The only way to
get rid of the overfull boxes is to change the tolerance, i.e., to allow
wider spaces between words. Indeed, the tolerance that plain \TeX\ uses
for wide lines is completely inappropriate for 2-inch columns; such narrow
columns simply can't be achieved without loosening the constraints, unless
you rewrite the copy to fit.

\TeX\ assigns a numerical value called ``↑{badness}'' to each line that
it sets, in order to asses the quality of the spacing. The exact rules
for badness are different for different fonts, and they will be discussed
in a later chapter; but here is the way badness works for the roman font
of plain \TeX:
$$\displayvbox{\hbadness10000
    \halign{#\hfil&\hskip3em#\hfil\cr
      \hbox expand-.666667em{The badness of this line is 100.}&(very tight)\cr
      \hbox expand-.333333em{The badness of this line is 12.}&
       (somewhat tight)\cr
      \hbox{The badness of this line is 0.}&(perfect)\cr
      \hbox expand.5em{The badness of this line is 12.}&(somewhat loose)\cr
%\hbox expand 1em{The badness of this line is 100.}&(loose)\cr % then "looser"
      \hbox expand 1.259921em{The badness of this line is 200.}&(loose)\cr
%\hbox expand 1.713em{The badness of this line is 500.}\cr
      \hbox expand 2.155em{The badness of this line is 1000.}&(bad)\cr
      \hbox expand 3.684em{The badness of this line is 5000.}& % actually 4995!
       (awful)\cr}}$$
Plain \TeX\ normally stipulates that no line's badness should exceed 200;
but in our case, the task would be impossible since
$$\displayvbox{\hbadness 10000
\hbox{`\hbox to 2in{tant galaxy called \"O\"o\c c, there}'\hskip 3em
  has badness 1515;}
\hbox{`\hbox to 2in{he preferred to be called---was}'\hskip 3em
  has badness 552.}}$$
So we turn now to Experiment@4, in which spacing variations that are
more appropriate to narrow columns will be used.

Run \TeX\ again, and begin this time by saying
\ttbegin
\hsize=2in \tolerance=1600 \input story
\ttend
so that lines with badness up to 1600 will be tolerated. Hurray! there are
↑(*tolerance)
no overfull boxes this time. \ (But we do get a message about an {\sl
underfull\/} box, since \TeX\ reports all boxes whose badness exceeds
a certain threshold called ↑{*hbadness}; plain \TeX\ sets |\hbadness=1000|.) \
Now make \TeX\ work still harder by trying
\ttbegin
\hsize=1.5in \input story
\ttend
(thus leaving the tolerance at 1600 but making the ↑{column width} still
↑(measure, see hsize)
skimpier). Alas, overfull boxes return; so try typing
\ttbegin
\tolerance 10000 \input story
\ttend
in order to see what happens. \TeX\ treats 10000 as if it were ``infinite''
tolerance, allowing arbitrarily wide space; thus, a tolerance of 10000 will
{\sl never\/} produce an overfull box, unless something strange occurs like
an unhyphenatable word that is wider than the column itself.

Two boxes are reported underfull at the 1.5-inch setting; with such narrow
limits, occasional wide space is unavoidable. But try
\ttbegin
\raggedright \input story
\ttend
for a change. \ ↑(:raggedright)(This tells \TeX\ not to worry about keeping
the right margin straight, and to keep the spacing uniform within each line.) \
Finally, type
\ttbegin
\hsize=.75in \input story
\ttend
followed by `|\end|', to complete Experiment 4. This makes the columns
almost impossibly small.

\danger The output from this experiment will give you some feeling for the
problem of breaking a paragraph into approximately equal lines. When the
lines are relatively wide, \TeX\ will almost always find a good solution.
But otherwise you will have to figure out some compromise, and several options
are possible. Suppose you want to ensure that no lines have badness
exceeding@500. Then you could set |\tolerance| to some high number, and |\hbadness=500|;
\TeX\ would not produce overfull boxes, but it would warn you about the
underfull ones. Or you could set |\tolerance=500|; then \TeX\ might produce
overfull boxes. If you really want to take corrective action, the second
alternative is better, because you can look at an overfull box to see
how much sticks out; it becomes graphically clear what remedies are possible.
On the other hand, if you don't have time to fix bad spacing---if you just
want to know how bad it is---then the first alternative is better.

\dangerexercise When |\raggedright| has been specified, badness reflects
the amount of space at the right margin, instead of the spacing between
words. Devise an experiment by which you can easily determine what
badness \TeX\ assigns to each line, when the |story| is set ragged-right
in 1.5-inch columns.
\answer Run \TeX\ with \hbox{|\hsize=1.5in|} \hbox{|\tolerance=10000|}
\hbox{|\raggedright|} \hbox{|\hbadness=-1|} and then |\input story|. \TeX\ will
report the badness of all lines (except the final lines of paragraphs, where
fill glue makes the badness zero).

\danger A parameter called ↑{*hfuzz} allows you to ignore boxes that are only
slightly overfull. For example, if you say |\hfuzz=1pt|, a box must stick
out more than one point before it is considered erroneous. Plain \TeX\
sets |\hfuzz=0.1pt|.

\dangerexercise Inspection of the output from Experiment@4, especially
page@3, shows that with narrow columns it would be better to allow white
space to appear before and after a dash, whenever other spaces in the
same line are being stretched. Define a ↑{:dash} macro that does this.
\answer |\def\extraspace{\nobreak \hskip 0pt plus .15em }|\par
|\def\dash{\unskip\extraspace---\extraspace}|\par
(If you try this with the story at 2-inch and 1.5-inch sizes, you will
notice a substantial improvement. The |\unskip| allows people to leave a
space before typing |\dash|.  \TeX\ will try to hyphenate before |\dash|,
but not before `|---|'; cf.\ Appendix@H.)

You were warned that this is a long chapter. But take heart: there's only
one more experiment to do, and then you will know enough about \TeX\ to
run it fearlessly by yourself. The only thing you are still missing is some
information about how to cope with error messages, i.e., not just with
warnings about things like overfull boxes, but with cases where \TeX\
actually stops and asks you what to do next.

{Error messages} can be terrifying when you aren't prepared for them;
but they can be fun when you have the right attitude. Just remember that
you really haven't hurt the computer's feelings, and that nobody will
hold the errors against you. Then you'll find that running \TeX\ might
actually be a creative experience instead of something to dread.

The first step in Experiment 5 is to plant two intentional mistakes in the
|story.tex| file. Change line@3 to
\ttbegin
\ctrline{\bf A SHORT \ERROR STORY}
\ttend
and change `|\vskip|' to `|\vship|' on line@2.

Now run \TeX\ again; but instead of `|story|' type `|sorry|'. The computer
should respond by saying that it can't find file |sorry.tex|, and it will
ask you to try again. Just hit \<carriage-return> this time; you'll see
that you had better give the name of a real file. So type `|story|' and
wait for \TeX\ to find one of the {\sl faux pas\/} in that file.

Ah yes, the machine will soon stop\footnote*{Some installations of \TeX\ do
not allow interaction. In such cases all you can do is look at the error
messages on your log file, where they will appear together with the ``help''
information.}, after typing something like this:
\ttbegin
! Undefined control sequence.
l.2 \vship
           1in
?
\ttend
\TeX\ begins its ↑{error messages} with ``|!|'', and it shows what it was
reading at the time of the error by displaying two lines of context. The
top line of the pair (in this case `|\vship|'\thinspace) shows what \TeX\
has looked at so far; and the bottom line (in this case `|1in|'\thinspace)
shows what \TeX\ has yet to read.

The `↑{.?}' that appears after the context display means that \TeX\ wants
advice about what to do next. If you've never seen an error message before,
or if you've forgotten what sort of response is expected, you can type
`|?|' now (go ahead and try it!); \TeX\ will respond as follows:
\ttbegin
Type <return> to proceed, S to scroll future error messages,
R to run without stopping, Q to run quietly,
I to insert something, E to edit your file,
1 or ... or 9 to ignore the next 1 to 9 tokens of input,
H for help, X to quit.
\ttend
This is your menu of options. You may choose to continue in various ways:

\smallskip\item{1)}
Simply type \<carriage-return>. \TeX\ will resume its processing, after
attempting to recover from the error as best it can.

\smallbreak\item{2)} Type `|S|'. \TeX\ will proceed as in (1), but without
pausing for instructions if further errors arise. Subsequent error messages
will flash by on your terminal, possibly faster than you read them, and
they will appear on your log file where you can scrutinize them at your
leisure. Thus, `|S|' is sort of like typing \<carriage-return> to every
message.

\smallbreak\item{3)} Type `|R|'. This is like `|S|' but even stronger,
since it tells \TeX\ not to stop for any reason, not even if a file name
can't be found.

\smallbreak\item{4)} Type `|Q|'. This is like `|R|' but even more so,
since it tells \TeX\ not only to proceed without stopping but also to
suppress all further output to your terminal. It is a fast, but somewhat
reckless, way to proceed (intended for running \TeX\ with no operator in
attendance).

\smallbreak\item{5)} Type `|I|', followed by some text that you want to
insert. \TeX\ will read this text before encountering what it would ordinarily
see next. Lines of text inserted in this way are not assumed to end with a
blank space.

\smallbreak\item{6)} Type a small number. \TeX\ will delete this many
characters and control sequences from whatever it is about to read next,
and it will pause again to give you another chance to look things over.

\smallbreak\item{7)} Type `|H|'. This is what you should do now and whenever
you are faced with an error message that you haven't seen for awhile. \TeX\
has two messages built in for each perceived error: a formal one and an
informal one. The formal message is printed first (e.g., `|! Undefined
control sequence.|'\thinspace); the informal one is printed if you request
more help by typing `|H|', and it also appears in your log file if you
are scrolling error messages. The informal message tries to complement the
formal one by explaining what \TeX\ thinks the trouble is, and often
by suggesting a strategy for recouping your losses.↑(help messages)

\smallbreak\item{8)} Type `|X|'. This causes \TeX\ to stop working on your
job, after putting the finishing touches on your |log| file and on any
pages that have already been output to your |dvi| file.

\smallbreak\item{9)} Type `|E|'. This is like `|X|', but it also prepares
the computer to edit the file that \TeX\ is currently reading, at the
current position, so that you can conveniently make a change before
trying again.

\smallbreak\noindent
After you type `|H|' (or `|h|', which also works), you'll get a message
that tries to explain that the control sequence just read by \TeX\
(i.e., |\vship|) has never been assigned a meaning, and that you should
either insert the right control sequence or you should go on as if the offending
one had not appeared.

In this case, therefore, your best bet is to type
\ttbegin
I\vskip
\ttend
(and \<carriage-return>); this effectively replaces |\vship| by
|\vskip|. \ (Do it.)

If you had simply typed \<carriage-return> instead of
inserting anything, \TeX\ would have gone ahead and read `|1in|', which
it would have regarded as part of a paragraph to be typeset. Alternatively,
you could have typed `|3|'\thinspace; that would have deleted
`|1in|' from \TeX's input. Or you could have typed `|X|' or `|E|' in
order to correct the spelling error in your file. But it's usually
best to try to detect as many errors as you can, each time you run \TeX,
since that increases your productivity while decreasing your computer bills.
Chapter@27 explains more about the art of steering \TeX\ through
troubled text.

\dangerexercise What would have happened if you had typed `|5|' after
the |\vship| error?
\answer \TeX\ would have deleted five tokens: |1|, |i|, |n|, \vspace, |\ctrline|.
(The space was at the end of line@2, the |\ctrline| at the beginning
of line@3.)

\danger You can control the level of interaction by giving commands
in your file as well as online: The \TeX\ primitives ↑{*scrollmode},
↑{*nonstopmode}, and ↑{*batchmode} correspond respectively to typing
`|S|', `|R|', or `|Q|' in response to an error message, and
↑{*errorstopmode} puts you back into the normal level of interaction. \
(Such changes are global, whether or not they appear inside a group.) \
Furthermore, many installations have implemented a way to ↑{interrupt}
\TeX\ while it is running; such an interruption causes the program to
revert to |\errorstopmode|, after which it pauses and waits for
further instructions.

What happens next in Experiment 5? \TeX\ will hiccup on the other bug that
we planted in the file. This time, however, the error message is more
elaborate, since the context appears on six lines instead of two:
\ttbegin
! Undefined control sequence.
<argument> \bf A SHORT \ERROR
                              STORY
\ctrline #1->\line {\hss #1
                           \hss }
l.3 \ctrline{\bf A SHORT \ERROR STORY}
|null
?
\ttend
You get multiline error messages like this when the error is detected
while \TeX\ is processing some higher-level commands---in this case,
while it is trying to carry out |\ctrline|, which is not a primitive
operation (it is defined in plain \TeX). At first, such error
messages will appear to be complete nonsense to you, because much of what
you see is low-level \TeX\ code that you never wrote. But you can overcome
this hangup by getting a feeling for the way \TeX\ operates.

First notice that the context information always appears in pairs of lines.
As before, the top line shows what \TeX\ has just read (\thinspace
`|\bf A SHORT \ERROR|'\thinspace), then comes what it is about to read
(\thinspace`|STORY|'\thinspace). The next pair of lines shows the context
of the first two; it indicates what \TeX\ was doing just before it began to
read the others. In this case, we see that \TeX\ has just read `|#1|', which
is a special code that tells the machine to ``read the first ↑{argument} that
is governed by the current control sequence''; i.e., ``now read the stuff that
↑{:ctrline} is supposed to center on a line.'' The definition in Appendix@B
says that |\ctrline|, when applied to some text, is supposed to be carried
out by sticking that text in place of the `|#1|' in `|\line{\hss#1\hss}|'.
So \TeX\ is in the midst of this expansion of |\ctrline|, as well as being
in the midst of the text that is to be centered.

The bottom line shows how far \TeX\ has gotten so far in the |story| file.
\ (Actually the bottom line is blank in this example; what appears to be
the bottom line is really the first of two lines of context, and it
indicates that \TeX\ has read everything including the `|}|' in line@3 of
the file.) \ Thus, the context in this error message gives us a glimpse of
how \TeX\ went about its business. First, it saw |\ctrline| at the
beginning of line@3. Then it looked at the definition of |\ctrline| and
noticed that |\ctrline| takes an ``argument,'' i.e., that it applies to
the next character or control sequence or group that follows. So \TeX\
read@on, and filed `|\bf A SHORT \ERROR STORY|' away as the argument to
|\ctrline|.  Then it began to read the expansion, as defined in plain
\TeX\ (Appendix@B\null).  When it reached the |#1|, it began to read the
argument it had saved.  And when it reached |\ERROR|, it complained about
an undefined control sequence.

\dangerexercise Why would it have been a mistake for \TeX\ to complain about
|\ERROR| being undefined when |\ERROR| was first encountered, i.e., before
reading `|STORY}|' on line@3?
\answer A control sequence like |\ctrline| might well define a control
sequence like |\ERROR| before telling \TeX\ to look at |#1|.

When you get a multiline error message like this, the best clues about the
source of the trouble are usually on the bottom line (since that is what
you typed) and on the top line (since that is what triggered the error
message). Somewhere in there you can usually spot the problem.

Where should you go from here? If you type `|H|' now, you'll just get
the same help message about undefined control sequences that you saw
before. If you respond by typing \<carriage-return>, \TeX\ will go
on and finish the run, producing output virtually identical to that in
Experiment@2. In other words, the conventional responses won't teach you
anything new. So type `|E|' now; this terminates the run and prepares
the way for you to fix the erroneous file. \ (On some systems, \TeX\ will
actually start up the standard text editor, and you'll be positioned at
the right place to delete `|\ERROR|'. On other systems, \TeX\ will simply
tell you to edit line@3 of file |story.tex|.) ↑(editing)

When you edit |story.tex| again, you'll notice that line@2 still contains
|\vship|; the fact that you told \TeX\ to insert |\vskip| doesn't mean
that your file has changed in any way. In general, you should correct all
errors in the input file that were spotted by \TeX\ during a run; the
transcript file provides a handy way to remember what those errors were.

\smallskip
Well, this has indeed been a long chapter, so let's summarize what has
been accomplished. By doing the five experiments you have learned at first
hand (1)@how to get a job printed via \TeX; (2)@how to make a file that
contains a complete \TeX\ manuscript; (3)@how to change the plain \TeX\
format to achieve columns with different widths; and (4)@how to avoid
panic when \TeX\ issues stern@warnings.

So you could now stop reading this book and go on to print a bunch of
documents. It is better, however, to continue bearing with the author
(after perhaps taking another rest), since you're just at the threshold
of being able to do a lot more. While reading the remaining chapters
it will, of course, be best for you to continue making trial runs,
using experiments of your own design.

\chapterend

What we have to learn to do we learn by doing.
\author ↑{ARISTOTLE}, {\sl Ethica Nicomachea\/} II (c.@325 B.C.)

\bigskip

He that runs may read.
\author WILLIAM ↑{COWPER}, {\sl Tirocinium\/} (1785)

\eject